/*
 * Copyright 2011 myTDev.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.mytdev.commons.action;

import java.beans.ExceptionListener;

/**
 * An Action is a Runnable that fails or succeeds. 
 * It has a state which is PENDING before it runs, STARTED while running and 
 * DONE when its execution is finished.
 * 
 * @author Yann D'Isanto
 */
public interface Action extends Runnable {

    /**
     * Registers listener so that it will receive Exceptions thrown during the 
     * action execution.
     * @param listener the ExceptionListener to register
     */
    void addExceptionListener(ExceptionListener listener);

    /**
     * Returns this action result or null if this action is not done.
     * @return this action result or null if this action is not done.
     */
    Result getResult();
    
    /**
     * Returns this action state.
     * @return this action state. 
     */
    State getState();
    
    /**
     * Unregisters listener so that it will no longer receive Exceptions.
     * @param listener 
     */
    void removeExceptionListener(ExceptionListener listener);

    /**
     * The Action result enumeration
     */
    public static enum Result {

        FAILURE,
        SUCCESS;
    }

    /**
     * The Action state enumeration
     */
    public static enum State {

        DONE,
        PENDING,
        STARTED;
    }
}
